---
title: Global Configs
label: Globals
order: 30
desc: Set up your Global config for your needs by defining fields, adding slugs and labels, establishing access control, tying in hooks and more.
keywords: globals, config, configuration, documentation, Content Management System, cms, headless, javascript, node, react, nextjs
---

Globals are in many ways similar to [Collections](../configuration/collections), except that they correspond to only a single Document. You can define as many Globals as your application needs. Each Global Document is stored in the [Database](../database/overview) based on the [Fields](../fields/overview) that you define, and automatically generates a [Local API](../local-api/overview), [REST API](../rest-api/overview), and [GraphQL API](../graphql/overview) used to manage your Documents.

Globals are the primary way to structure singletons in Payload, such as a header navigation, site-wide banner alerts, or app-wide localized strings. Each Global can have its own unique [Access Control](../access-control/overview), [Hooks](../hooks/overview), [Admin Options](#admin-options), and more.

To define a Global Config, use the `globals` property in your [Payload Config](./overview):

```ts
import { buildConfig } from 'payload'

export default buildConfig({
  // ...
  globals: [ // highlight-line
    // Your Globals go here
  ],
})
```

<Banner type="success">
  <strong>Tip:</strong>
  If you have more than one Global that share the same structure, consider using a [Collection](../configuration/collections) instead.
</Banner>

## Config Options

It's often best practice to write your Globals in separate files and then import them into the main [Payload Config](./overview).

Here is what a simple Global Config might look like:

```ts
import { GlobalConfig } from 'payload'

export const Nav: GlobalConfig = {
  slug: 'nav',
  fields: [
    {
      name: 'items',
      type: 'array',
      required: true,
      maxRows: 8,
      fields: [
        {
          name: 'page',
          type: 'relationship',
          relationTo: 'pages', // "pages" is the slug of an existing collection
          required: true,
        },
      ],
    },
  ],
}
```

<Banner type="success">
  <strong>Reminder:</strong>
  For more complex examples, see the [Templates](https://github.com/payloadcms/payload/tree/main/templates) and [Examples](https://github.com/payloadcms/payload/tree/main/examples) directories in the Payload repository.
</Banner>

The following options are available:

| Option              | Description                                                                                                                                                                                    |
| ------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **`access`**        | Provide Access Control functions to define exactly who should be able to do what with this Global. [More details](../access-control/globals).                                                  |
| **`admin`**         | The configuration options for the Admin Panel. [More details](../admin/globals).                                                                                                               |
| **`custom`**        | Extension point for adding custom data (e.g. for plugins)                                                                                                                                      |
| **`dbName`**        | Custom table or collection name for this Global depending on the Database Adapter. Auto-generated from slug if not defined.                                                                    |
| **`description`**   | Text or React component to display below the Global header to give editors more information.                                                                                                   |
| **`endpoints`**     | Add custom routes to the REST API. [More details](../rest-api/overview#custom-endpoints).                                                                                                      |
| **`fields`** \*     | Array of field types that will determine the structure and functionality of the data stored within this Global. [More details](../fields/overview).                                            |
| **`graphQL.name`**  | Text used in schema generation. Auto-generated from slug if not defined.                                                                                                                       |
| **`hooks`**         | Entry point for Hooks. [More details](../hooks/overview#global-hooks).                                                                                                                         |
| **`label`**         | Text for the name in the Admin Panel or an object with keys for each language. Auto-generated from slug if not defined.                                                                        |
| **`lockDocuments`** | Enables or disables document locking. By default, document locking is enabled. Set to an object to configure, or set to `false` to disable locking. [More details](../admin/locked-documents). |
| **`slug`** \*       | Unique, URL-friendly string that will act as an identifier for this Global.                                                                                                                    |
| **`typescript`**    | An object with property `interface` as the text used in schema generation. Auto-generated from slug if not defined.                                                                            |
| **`versions`**      | Set to true to enable default options, or configure with object properties. [More details](../versions/overview#globals-config).                                                               |

_\* An asterisk denotes that a property is required._

### Fields

Fields define the schema of the Global. To learn more, go to the [Fields](../fields/overview) documentation.

### Access Control

[Global Access Control](../access-control/globals) determines what a user can and cannot do with any given Global Document. To learn more, go to the [Access Control](../access-control/overview) documentation.

### Hooks

[Global Hooks](../hooks/globals) allow you to tie into the lifecycle of your Documents so you can execute your own logic during specific events. To learn more, go to the [Hooks](../hooks/overview) documentation.

### Admin Options

You can customize the way that the [Admin Panel](../admin/overview) behaves on a Global-by-Global basis. To learn more, go to the [Global Admin Options](../admin/globals) documentation.

## TypeScript

You can import types from Payload to help make writing your Global configs easier and type-safe. There are two main types that represent the Global Config, `GlobalConfig` and `SanitizeGlobalConfig`.

The `GlobalConfig` type represents a raw Global Config in its full form, where only the bare minimum properties are marked as required. The `SanitizedGlobalConfig` type represents a Global Config after it has been fully sanitized. Generally, this is only used internally by Payload.

```ts
import type { GlobalConfig, SanitizedGlobalConfig } from 'payload'
```
